Archive Magazine CD 1995

home *** CD-ROM | disk | FTP | other *** search

/ Archive Magazine CD 1995 / Archive Magazine CD 1995.iso / discs / prog_disc / volume_1 / issue_11 / arc / arcdoc < prev

Wrap

Text File | 1995-06-13 | 17.5 KB | 446 lines

************************************************************ * * * Beebug * * * * A R C H I M E D E S * * * * AA RRRRRRRR CCCCCC * * AA AA RR RR CC CC * * AA AA RR RR CC * * AAAAAAAAAA RRRRRRRR CC * * AA AA RR RR CC * * AA AA RR RR CC CC * * AA AA RR RR CCCCCC * * * * * * by David Pilling * * * * * * This program is Public Domain * * * ************************************************************ ****************************************************************************** * * * ARC Version Numbers * * ------------------- * * * * Version 1.0 - 29/06/88 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ****************************************************************************** Archimedes ARC Page 2 Contents -------- (1) Introduction (2) How to use ARC (3) ARC commands (4) Archimedes ARC file format (5) ARC support 1. Introduction --------------- ARC is the Archimedes archive utility. An archive is a file in which many smaller files are stored. You may, using the ARC utility, create archives and add files to them (ARC'ing a file) or remove files (de-ARC'ing). One of the features of ARC, is that files are stored in a highly compressed form; thus saving disc space and allowing more rapid transfer of files by modem. However, probably the most useful feature of an archive is that like sub-directories in the ADFS, it makes keeping track of files when transferring them from one machine to another, much simpler. Archives have a long history going back to UNIX and CP/M. An example of an archive with no compression is the UNIX shar format. Whilst on CP/M archive utilities which used data compression include squeeze, LUE and LBR. Perhaps the most well known archive format and utility is the System Enhancements Associates (SEA) ARC for the IBM PC which was based on many of these earlier programs. This has now been transferred to the Atari ST and Amiga micros. In addition, other more advanced versions of it have appeared on the PC like PKARC by Phil Katz. Beebug Archimedes ARC is fully compatible with SEA's ARC program. Using it, you can successfully unpack PC archives on your Archimedes, as well as create PC format archives. In addition, you can use a special Archimedes format archive which while not compatible with the PC, preserves Archimedes file attributes like load and exec addresses. If you dial up your local bulletin board, you will see many ARC files (they are usually identified by the suffix .ARC). Using ARC, you will be able to transfer the files in these to your Archimedes. Obviously, you cannot use executable PC programs, but there are many text and data files which you may want to examine (such as documentation, C source files, screen images etc.). Do not get the impression from the above, that the data compression aspect of ARC is just a side effect. Frequently, you may achieve a space saving of upto 90%. Just how much space you save, depends on the type of file being ARC'd. Text files usually compress well. Whilst PC executable files rarely compress by much, Archimedes Basic programs seem to show good savings in space (often owing to Acorn's way of handling arrays). Archimedes ARC Page 3 2. How to use ARC ----------------- Archimedes ARC consists of two files: the program ARC, and ARC_DOC containing this text. You use ARC by typing *arc followed by a number of parameters. If you type *arc on its own without parameters, a page of help information is displayed. For example: *arc Archimedes ARC - Archive utility Usage: ARC {amufdxeplt}[bswnoi][g<password>] <archive> [<filename> . . .] Where: a = add files to archive m = move files to archive u = update files in archive f = freshen files in archive d = delete files from archive x,e = extract files from archive p = print file to screen l = listing of files in archive t = test archive integrity b = retain backup copy of archive s = suppress compression (store only) w = suppress warning messages n = suppress notes and comments o = overwrite existing files when extracting i = Use IBM PC Archive format g = Encrypt/decrypt archive entry Written for the Archimedes by David Pilling Put in the Public Domain by BEEBUG V1.00 July 1988 Although the syntax of the ARC program may look a little frightening at first, it is really quite straightforward. Typically you will almost always use just a few of these options. The letters which appear after 'ARC', split into two groups; commands amufdxeplt and options bswnoi and g. In general, you should have just one command letter and as many options as you need. The next section looks at the commands and options. Archimedes ARC Page 4 3. ARC commands --------------- a = add files to archive This command is used to add files to an archive. If the archive does not exist, it is automatically created. An example of this command is: *arc a utils_arc util1 util2 util3 util4 This adds the files util1, util2 etc. to the archive utils_arc. You can use wildcards in this command as follows: *arc a my_arc b* This will add all files whose names begin with 'b' to the archive. You can use any legal filename for the name of the archive, but we recommend that you add the suffix '_arc' to the end of the name. This will help you identify ARC files. In addition, ARC files can also be identified by their filetype, which is set to &DDC (Acorn approved filetype). m = move files to archive This command is like 'a' except that the files are deleted from the local filing system as they are added to the archive file. u = update files in archive This only adds files to the archive if the versions on disc have a more recent date stamp, or if they are not already in the archive. For example: *arc u my_arc will update all files in the current directory that have been created or changed since they were last archived. f = freshen files in archive This is like the 'a' command, except that files are only added if they already exist in the archive with an earlier date stamp. d = delete files from archive This command allows you to delete files from an archive. For example: *arc d my_arc bob will remove the file bob from the archive file. Archimedes ARC Page 5 x,e = extract files from archive These two commands, remove files from an archive and create them in a usable form on your disc. For example; *arc x my_arc util1 recreates the file 'util1' from the archive. Notice that 'util1' remains part of the archive. If you want to extract all the files, simply type: *arc x my_arc p = print file to screen This is very similar to 'x' and 'e' except that the file is printed out on the screen, instead of being sent to the filing system. l = listing of files in archive This very useful command shows you the contents of an archive along with much useful information. For example, to see the contents of the archive called 'my_arc', type: *arc l my_arc You can, of course, specify individual files or groups of files using wildcards. For example: *arc l my_arc pr* The information displayed gives the original length of the file, and how long it is in its compressed form. The time and date stamps for the file and information on which form of data compression has been used to store the file. You will notice that this is preceded by either 'PC' or 'ARC', which indicates whether the file is stored in PC or Archimedes format. t = test archive integrity A CRC (Cyclic Redundancy Check) is kept for each file added to the archive, this allows ARC to tell you if a file has been corrupted. This can happen when you are transferring files between different computers. The 't' command unpacks all of the archive entries (without saving them anywhere), and checks the CRC for each file against the recorded value. It reports back to you any damage to the archive. For example, to test that the archive 'my_arc' has been recieved correctly, type: *arc t my_arc Archimedes ARC Page 6 b = retain backup copy of archive When you add a file to an archive, the original archive is renamed to B_oldname. Normally, this is deleted after the file has been succesfully added. By using the 'b' option, you can keep a copy of the original archive. For example, if you wanted to add the file 'program' to the archive 'my_arc', but want to keep a backup copy of the archive, then type: *arc ab my_arc program The backup archive is called 'b_my_arc'. s = suppress compression (store only) This allows you to add files to the archive without compressing them. w = suppress warning messages This option prevents warning messages being printed. n = suppress notes and comments This option suppresses notes and comments. o = overwrite existing files when extracting When you extract a file, it may be that a file with the same name already exists. Normally, you will be prompted to overwrite the file. If you then select N, you will be prompted for permission to rename the file. If you then select Y, ARC will pick a sensible name, but if you select N, ARC will continue to the next file to be extracted. The 'o' option allows you to prevent all prompting, and just overwrite existing files. For example: *arc xo my_arc i = Use IBM PC Archive format When you add a file to an archive, ARC assumes that you want the file to be stored with its load and exec addresses and attributes. However, if you want to give an archive to a friend with a PC, you should store the files in PC format by adding the 'i' option to the command line. For example, to add a PC file to an archive, type: *arc ai my_arc PCprog Archimedes ARC Page 7 g = Encrypt/decrypt archive entry The 'g' (garble) option allows you to give a password which is used to encrypt files stored in the archive. The data compression normally applied will make files unreadable using *TYPE or *DUMP, this lets only people who know the password extract them from the archive. For example, if you wish to add 'newfile' to the archive 'my_arc', and encrypt it using the password 'beebug', type: *arc agbeebug my_arc newfile When you want to extract the file again, you should type: *arc xgbeebug my_arc newfile The password can be any length, and is not case sensitive. You can if you wish use different passwords for each file in an archive, but we advise against it. If you should forget or mistype your password, it is unlikely that you will ever recover the file. Archimedes ARC Page 8 4. Archive file format ---------------------- An Archive, is a binary file consisting of archive markers, archive headers and file data. All archives are preceded by an archive marker. This is a single byte of value 27. An archive header, consists of several bytes. byte 1 Header version number. This tells you how the file data is stored and how many bytes there are in the header. The header version numbers for the PC, are detailed below. An Archimedes header version number is identical to the corresponding PC number except it has bit 7 set. bytes 2-15 Filename bytes 16-19 Compressed file length bytes 20,21 File date stamp bytes 22,23 File time stamp bytes 24,25 CRC for the file bytes 26-29 If the header type is greater than 1, these hold the original file length otherwise they are not present. bytes 30-33 If bit 7 of the header version number is set, these bytes hold the Archimedes load address for the file otherwise they are not present. bytes 34-37 If bit 7 of the header version number is set, these bytes hold the Archimedes exec address for the file otherwise they are not present. bytes 38-41 If bit 7 of the header version number is set, these bytes hold the Archimedes file attributes otherwise they are not present. The archive header, is followed by the file data. The file data is followed by another archive marker The archive finishes with an archive marker followed by a zero byte. The time and date fields are always filled in. If the file has a load and exec address, these are the time and date when the file was added to the archive otherwise, they are derived from the Archimedes datestamp. In all extract operations on Archimedes format archives, the contents of the load and exec fields take precedence. PC and ARC formats may be mixed in one archive for use on the Archimedes. Archimedes ARC Page 9 PC ARC Header version numbers: 1 = Old style, no compression 2 = New style, no compression 3 = Compression of repeated characters only 4 = Compression of repeated characters plus Huffman Squeezing 5 = Lempel-Zev packing of repeated strings (old style) 6 = Lempel-Zev packing of repeated strings (new style) 7 = Lempel-Zev Williams packing with improved hash function 8 = Dynamic Lempel-Zev packing with adaptive reset The time and date stamps are two byte values from which the time in years etc., can be found as follows; year = (date >> 9) & 0x7f; month = (date >> 5) & 0x0f; day = date & 0x1f; hour = (time >> 11) & 0x1f; minute = (time >> 5) & 0x3f; second = (time & 0x1f) * 2; Where years are offset from 1980, months begin with 1=January. Archimedes ARC Page 10 5. ARC support -------------- Please send any comments or suggestions for ARC to the address below. In addition, if you would like details of the latest version of ARC and how to get hold of a copy, please contact: Software Manager Beebug Ltd. Dolphin Place, Holywell Hill, St. Albans, Herts. AL1 1EX Tel. (0727) 40303